Skip to content

Check the docs against the files they copy from - #43

Merged
dmccoystephenson merged 1 commit into
mainfrom
feature/check-docs-against-sources
Nov 7, 2026
Merged

dmccoystephenson merged 1 commit into
mainfrom
feature/check-docs-against-sources

Conversation

@dmccoystephenson

@dmccoystephenson dmccoystephenson commented Nov 7, 2026 •

Copy link
Copy Markdown
Member

Summary

  • DocumentationTest is added. It reads the Markdown docs alongside minecraft-versions.json, Main.java and plugin.yml, and fails the build when the version lists, /fly messages or FlyCommand.fly permission details disagree. The strings are taken from the sources, so the test needs no editing when a message changes.
  • The README's Testing section and project layout now describe the new tests.
  • The README no longer says the suite reads the plugin.yml "packed into the jar". The build log shows surefire running before maven-jar-plugin, so no jar exists at that point.
  • No plugin code, manifest or workflow is changed, and no doc claim other than the one above needed correcting: the docs already agree with their sources.

Closes #42

Validation

mvn -B clean package on the PR head: Tests run: 13, Failures: 0, Errors: 0, Skipped: 0, BUILD SUCCESS (10 existing tests, 3 new).

The new tests were confirmed able to fail. Each mutation below was applied alone, mvn clean test was run, and the file was restored:

Mutation Caught by
minecraft-versions.json gains 26.4 versionListsMatchMinecraftVersionsJson
minecraft-versions.json loses 26.3 versionListsMatchMinecraftVersionsJson
README.md list loses 26.3 versionListsMatchMinecraftVersionsJson
USER_GUIDE.md version typo versionListsMatchMinecraftVersionsJson
Message changed in Main.java docsQuoteEveryMessageTheCommandSends, plus two existing FlyCommandTest tests
Message reworded in COMMANDS.md docsQuoteEveryMessageTheCommandSends
Console alert reworded in README.md docsQuoteEveryMessageTheCommandSends
Default changed in plugin.yml docsNameEveryPermissionTheCommandChecks, plus PluginManifestTest.declaresTheFlyPermission
Default changed in USER_GUIDE.md docsNameEveryPermissionTheCommandChecks
Permission renamed in COMMANDS.md docsNameEveryPermissionTheCommandChecks
Permission dropped from CONFIG.md docsNameEveryPermissionTheCommandChecks

Nine of the eleven were not caught by the existing test suite.

No on-server recipe applies, because no plugin behaviour changes.

Known limit: the message and permission checks cover only strings Main.java passes as literals. A message built at runtime would not be seen; Main.java has none today.

Side effect of merging

src/test/** is not in the paths-ignore list of dev-release.yml, so merging republishes the dev prerelease, built from unchanged plugin code.

Deferred issues

This PR description was drafted during a Gardener session (https://github.com/Stephenson-Software/gardener).

🤖 Generated with Claude Code


drafted by Claude on behalf of Daniel Stephenson

The supported versions, the /fly messages and the permission details are
copied by hand into the Markdown docs, and nothing compared the copies with
minecraft-versions.json, Main.java or plugin.yml. DocumentationTest reads
both sides and fails the build when they disagree.

Also corrects the README, which said the suite reads the plugin.yml packed
into the jar: surefire runs before the jar is built.

Closes #42

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@dmccoystephenson

Copy link
Copy Markdown
Member Author

Self-review

Reviewed at 8a2d30d. This is a self-review, not an independent one.

The rubric below is scored against the Maven suite and the Build workflow, which now carry real signal. The skill's "no build system" premise is out of date for this repo; that gap is already tracked as Dans-Plugins/flycommand-dev-loop#8.

  • Anchor: PASS. mvn -B clean package printed Tests run: 13, Failures: 0, Errors: 0, Skipped: 0 and BUILD SUCCESS. Build run 42360363251 has headSha 8a2d30d, with both Build with Maven and Check Bukkit API use against every supported Minecraft version at success.
  • Scope: PASS. The diff is three files, all needed for Nothing checks the docs' version list, /fly messages and permission default against their sources #42: the test, the README text describing the suite, and a changelog bullet.
  • Validation-new: PASS. All 11 mutations in the PR description failed the suite when applied alone, and each mutated string was asserted present before the mutation.
  • Validation-fix: PASS for the README correction. Surefire running before maven-jar-plugin was read from the build log; no test covers this sentence.
  • Sibling structure: PASS. The test class follows the neighbouring test classes: package-private class, 4-space indent, class Javadoc stating why it exists.
  • Sibling renames: not applicable. Nothing was renamed.
  • Docs: PASS. The Testing section and project layout were updated. CONTRIBUTING.md, COMMANDS.md, CONFIG.md and USER_GUIDE.md make no claim this changes, and .github/copilot-instructions.md remains accurate.
  • Issue resolution: PASS. All three facts in the Nothing checks the docs' version list, /fly messages and permission default against their sources #42 table and the README correction are covered.
  • Manifest declaration, command declaration, main-class resolution: PASS. plugin.yml is unchanged and PluginManifestTest is green.
  • Override annotations: not applicable. Main.java is unchanged.
  • No stack change: PASS. No dependency was added; pom.xml is unchanged.
  • Changelog: PASS. One bullet was added under ## [Unreleased], ### Added.
  • No harness leakage: PASS. git diff --name-only origin/main HEAD lists only CHANGELOG.md, README.md and src/test/java/me/Daniel/FlyCommand/DocumentationTest.java.
  • Do-not-auto-merge paths: PASS. No listed path is modified.

Findings, none blocking:

  • src/test/java/me/Daniel/FlyCommand/DocumentationTest.java:59 — sendMessage\("([^"]+)"\) sees only string literals, so a message built by concatenation, or one containing an escaped quote, would be skipped without failing. Main.java has neither today; a message constant would need this pattern changed. The limit is stated in the PR description.
  • src/test/java/me/Daniel/FlyCommand/DocumentationTest.java:76 — the COMMANDS.md row is hard-coded to /fly. That matches the single command the plugin has, and a second command would need this test extended.
  • src/test/java/me/Daniel/FlyCommand/DocumentationTest.java:51 — the version list is found by the word currently, so rewording that sentence fails the build. This is deliberate: a list the test cannot find should not pass silently. The sentence pom.xml has sat at release version 1.0.1 since #30 with no v1.0.1 release #36 says to remove at the next release is separate from the list and does not affect the match.

This comment was drafted during a Gardener session (https://github.com/Stephenson-Software/gardener).


drafted by Claude on behalf of Daniel Stephenson

@dmccoystephenson
dmccoystephenson merged commit 6b93806 into main Nov 7, 2026
1 check passed
@dmccoystephenson
dmccoystephenson deleted the feature/check-docs-against-sources branch November 7, 2026 09:36
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Nothing checks the docs' version list, /fly messages and permission default against their sources

1 participant